Users' guide for V_Sim

Interface - the two windows↑ Return to top

The interface is divided into two windows. The one where the image is rendered is called the rendering window. It shows the loaded file. A small status bar stands on its bottom and gives some informations. The second window is called the command panel. It hosts all tools available with V_Sim.

These two windows have different X names (under X11), then the window manager can be used to store their size and position (see 'advanced properties' of Kwin or 'remember' menu option in Fluxbox for instance).

From version 3.5, the two windows can be gathered into one, or the command panel may not be created:

• -w --window-mode mode

  By default the command panel and the rendering window are separated. In the 'oneWindow' mode they are joined. In the 'renderOnly' mode, the command panel is not used.

Interface - the subpanels↑ Return to top

All tools available in V_Sim are gathered in different tabs called subpanels. These tabs are all hosted by the command panel, but they can be detached to act as floating utility windows (as in Gimp or Inkscape for instance). To do it, click on the little arrow on the right side of a tab header. It opens a menu that propose to create a new dock window to host the subpanel, or it gives a list of existing docks to send the subpanel to. It is also possible to hide the subpanel if it is not useful. The characteristics of docks windows (which subpanel they contain, their screen position, their size...) can be saved to the parameter file (see the related section).

Here is the list of tabs (as of version 3.6) and their capabilities:

• "Elements": for each represented element of the current file, set-up its rendering parameters (colour, shape, rendered...)
• "Frame/labels": this tab gathers the rendering parameters of all box related elements, like the bounding box itself (colour, pattern of line...), the drawn axis, the legend or possible scale marks.
• "Fog & bg": to tune the background colour, or add a background image and to tune the fog.
• "Browser": to navigate through the files.
• "Geometry": to change geometry related information, like the box translation or expansion, the box unit or some multi-file actions.
• "Data color": apply an external set of data to colourise nodes (plus some other post-treatments).
• "Planes": draw planes to cut the box, hide nodes...
• "Isosurfaces": load isosurfaces from files or from scalar fields.
• "Maps": assemblate planes and scalarfields to draw maps.
• "Phonons": manage phonon files and phonon animations.
• "Draw": choose the rendering method (atomic or spin) and setup parameters for it.
• "OpenGL": change the parameters related to the rendering model, adjust the light...
• "Configuration": some V_Sim global configuration parameters.

Interface - the command line options↑ Return to top

v_sim [options] [fileToRender]

The available options are detailed by typing 'v_sim --help', or 'man v_sim'.

The following table lists all the available options, their meaning and their syntax.

Usage↑ Return to top

There are three ways in V_Sim to open a crystal file (available formats are described later):

• From the command line, providing the path to a valid file;
• From the "open" buttons in the command panel or in the rendering window (Ctrl+O can be used as a shortcut):
• Or from the browser panel by double clicking on a file name from a given directory.

Change the units of a file↑ Return to top

If the file format gives unit information to V_Sim, the selector in the box subpanel will show the right value. If one select another unit, the corresponding factor will be applied on node positions and box size. All other values are kept equal. For instance, this is useful when all configuration files have been set up for Bohr units (pairs criterions...) but the loaded file is in angstöms.

In the configuration subpanel, one can choose his favorite unit. So when a file is loaded, the units are changed to always reflect this favorite value. This value is saved in the parameter file.

When the file format does not advertise any unit value, V_Sim is set to "undefined". The next selection of a unit will internally set the unit to this new value. Then one can do convertion as explained in the first paragraph.

Unit are exported when using a file format that can support it.

Translate and expand box↑ Return to top

In the box subpanel, and if the input file has periodic boundary conditions, the rendered system can be translated or expanded. For instance, XYZ files has no periodic information and these capabilities are disabled. The values for translation can vary from -1 to 1. and are given in reduced coordinates. The value for the expansion corresponds to the number of box duplication in each direction, both positive and negative. Float values are accepted. When the box is expanded, translation are kept but can be changed anymore. Uncheck the expansion to be able to change the translations again.

Expansion and translation are available from command line:

• -t --translate x:y:z

  It applies the given translation to the rendered file. {x, y, z} can be chosen in [-1;1].

• -x --expand x:y:z

  It applies the given expansion to the rendered file. {x, y, z} can be chosen in [0;3].

Automatic update↑ Return to top

When this option is enabled (see "configuration" subpanel), the program probes the disk for file changes and updates the drawing if necessary. The period for polling is adjustable and can vary from 100ms to 10s.

Max number of atoms↑ Return to top

There is NO max number of atoms. But, of course, if you visualize an atomic file with many atoms, drawing may become long time consuming thus, changing values on command panel may become difficult, because in "Immediate drawing mode", any change of values lead to a draw with the new values. In this case, use "Deferred drawing mode", and, when you have chosen your favourite values, use button "Redraw".

The program does not support more than NMAX_TP atom types (current implementation has NMAX_TP = 500). If you wish more, please contact Damien Caliste (damien.caliste A cea.fr).

The Rendering Atomic method - file formats↑ Return to top

V_Sim visualizes atomic files:

• in binary .d3 format as defined by Frédéric LANÇON (frederic DOT lancon AT cea.fr),
• in "ASCII" format as described by comments in ASCII demo.ascii sample file,
• in "xyz" format which is a plain text format.
• in "ETSF" format which is a binary format used to store results from electronic calculations (see ETSF page). This requires to load the associated plugin, available since version 3.3.
• in all formats supported by OpenBabel (see OpenBabel page). This requires to load the associated plugin, available since version 3.3.
• the XCrysDen file format, for atoms and forces. This requires to load the associated plugin, available since version 3.4.
• the ABINIT input file format. This requires to load the associated plugin, available since version 3.4 (and linkable with ABINIT source version 5.6). The datasets are supported.
• the Cube input file format. This requires to load the associated plugin, available since version 3.5.

The Rendering Atomic method - rendering shapes↑ Return to top

Elements can be rendered as spheres, which is the default behaviour. But other shapes are available. When a huge amount of elements must be rendered and look is not very important, one can choose the cubic shape or even the point shape. This last mode can be convenient also for representing grid points. The last available shape is the ellipsoid one. It can be used to make schemes when a direction must be highlighted. See the "Element" subpanel to change the shapes (1).

The orientation of the ellipsoid shape shape can be tuned per element (see (2)). Thus if orientation is important for each node of a given element, the spin method is more appropriated.

From version 3.5, a torus shape is also available. It follows the parameters of the ellipsoid shape. The two angles are used to orientate the torus. The main radius of the torus is the radius of the element and the ratio is used to obtain the internal radius.

The Rendering Spin method - Overview & basic options↑ Return to top

V_Sim can display spin configurations. Spin are represented as arrows, oriented and coloured according to the spin orientation of the node they represent. For each element arrow, you can specify many parameters such as its size, color or shape.

To set up V_Sim in "Spin Visualisation" mode, you must select this mode under the "Rendering method" subpanel (1). When this mode is selected, options relative to other modes are removed, and new ones appear, in this subpanel and in the "Element" one. You can then try to load a spin configuration to display.

The spin visualisation has several option. Basically elements can be represented by arrows, but atomic rendering can also be present when checkbox (2) is checked. By default, the modulus of spin is ignored. This behavior can by overridden with checkbox (3). When checked, the modulus is normalised to match the selected maximum length for arrows. The normalisation can be done per node types or for all of them. Finally, one can tune how spin with null modulus can be rendered (4): never (show elements with positive spin values), atomic (replace arrow by atomic rendering) or always (don't take care about modulus value).

The Rendering Spin method - Loading files↑ Return to top

To load a spin configuration (1), V_Sim reads two separate files. The first one is a "position file" (2), which contains each atoms position. Supported formats are exactly the same as the ones supported by the "Atomic Visualisation" mode (see the Atomic Visualisation mode documentation for more details). The "spin file" (3) contains each atoms spin information.

The Rendering Spin method - Coloration options↑ Return to top

Once you've selected your files, you should have your atomic configuration displayed on the screen. The first thing to understand is the bottom right color legend. Spins are coloured according to the HSL color space which is often represented as a "double conical" space. This cone is drawn to the bottom right of the screen if you chose to enable the axes. Two coloured areas are needed to get an exhaustive legend (1 & 2). The upper part represent the hidden area of the color cone (seen from the interior of the cone) (2).

You can set up coloration options under the "Config panel" (you need to click the "Show rendering option" label). "Rotate color wheel" (3) causes the cone to turn around its own rotation axis whereas the other options (4) allow the user to set the direction of this axis (in the main referential's coordinates). The "set ortho" button (5) sets the cone' axis to the current viewing direction. Notice all these options are saved along with the resources.

The Rendering Spin method - Elements options↑ Return to top

As in the "Atomic visualisation" mode, viewing options for each element can be set under the "Element" panel. From there, arrow properties can be changed according to user preferencies (1). Note they are saved along with resources. If you prefer to use normal coloration over spin coloration for an element, check the "Use element color for the ..." buttons (2). The available shapes are smooth arrows, edged arrows, ellipsoids (from version 3.2) and torus (from version 3.5).

Tip : the "Edged" shape for the arrow may seem ugly but it is a lot lighter than the "Rounded" shape, so try to use it if V_Sim is too slow on your computer. Notice the "Edged" shape is unaffected by the precision parameter set under the "Opengl" panel.

The Rendering Spin method - Command line options↑ Return to top

• -s --spin-file file

  If you want to directly load a spin configuration from the command line, you can use the following directive : v_sim -s spin_file position_file and V_Sim will try to load the given files as a spin configuration.

• -m --hiding-mode id

  You can also set whether you want to enable the "hiding_mode" (see spin overview & basic options). Possible values are: 0 to always hide spin with null modulus, 1 to always show them and 2 to represent them with there atomic shape. Default value is 0 (always hide).

Moving the camera↑ Return to top

The main interface of V_Sim is divided into two windows: the command panel and the rendering window. On this last window, the mouse is used to move the camera. This is called the observe mode. These mouse actions are possible:

• Rotate the view with a left click and mouse motions. The button must be kept pushed during the movements.
• Zoom in or zoom out, using the middle button and movements along Y axis. The mouse wheel can also be used if present.
• Changing the perspective is possible, using the middle button as in a zooming action but pressing the shift key in the same time. The mouse wheel can also be used if present (still with the shift key).
• Translate the position of the view using the shift key + left click and movements.
• The rotation the camera on itself can be used with control key + left click and movements. This should be used with care since in default observe mode, an angle different from 0 modulus 2pi is confusing.

Possible actions are summed up in the status bar on the bottom of the rendering window (2). It mentions that a simple pick action is available. To get informations on nodes right click on them. Available data are coordinates and node number. Distance can be directly measured in this default view, using the shift key + a right click. This will set a reference from which all further picked nodes will be compared to. To unset this reference, shift right click on nothing. From version 3.5, use control to set a second reference for angle measurements, and control + shift of shift for distance measurements, to be coherent with to hightlight a node.

The status bar contains also global informations (3) such as the window size or the number of nodes in the currently rendered file. If any commentary is present in the file, it is shown here. The buttons (4) are used to open a file (identical as the "open" button in the command panel), to refresh the view, to export the view in a bitmap format (or others if available) and the last is used to raise the command panel. From version 3.5, the refresh button is used to reload the file instead.

From version 3.5, there are there three icons on the right bottom part of the rendering window, as shown on the right.

• The magnifier icon (1) is used with right-click to show the list of saved camera positions. One can then choose a position. To save a camera position, use the key 's'. One can use the keyboard also to restore a previously saved camera position, using the key 'r'.
• The erase button (2) can be used to remove all persistant mark on the view, angles or distances.
• The property toggle button (3) can be used to set or unset mark on the last picked node (right click). When pushed, V_Sim, analyse the first neighbours and print all the distances and the angles in relation with the picked node.

The interactive window↑ Return to top

By clicking on the "pick & obs." button on the command panel, this last is replaced by a new window. This window gives access to detailed interactive mode. The most basic is the observe mode. It allows to move the camera as in default mode (when the command panel is presnt) but with access to detailled values. By right clicking, on can switch to another interactive mode, present in the current tab (1).

There are two observe mode (2):

• The constraint mode where the camera is moved along meridian lines (Y axis in mouse motion) and "equators" (X axis in mouse motion). The camera must always be oriented toward the north in this motion (omega value must be 0 modulus 2pi). This motion is convenient since whaever the movements, the system is kept oriented, but it becomes a bit confusing around the two "poles". This motion is the default.
• The walker mode where the camera is dragged as if on a sphere by a walking man. Pushing the mouse on the Y axis makes the man goes back or forward. Mouse motions along X axis makes the man turn left or right. In this mode, omega is no more constrained and free to be changed. This movement is more natural but it is hard to obtain the same views because of the omega variations.

In the bottom of this window, a small help frame (3) is present and always sum up the possible actions, whatever the current mode.

Playing with pick↑ Return to top

You can use several modes (all actions are detailed in the help frame). Picked information will then be printed into the area (1). Keyboard modifiers have been changed from version 3.5 to be coherent with the minimal pick mode of the rendering window in normal mode.

• get node informations (coordinates and number) using left-button ;
• get distances informations:
  1. Use shift middle-button to define a reference atom
  2. Use left-button to pick
  3. To change reference atom, go to first step. To cancel this distance measurement, go to first step (shift middle-button) while picking outside any atom.
• Pick to have both distances and angles informations:
  1. Use shift middle-button to define a reference atom
  2. Use control middle-button to define a 2nd reference atom
  3. Use left-button to pick
  4. To change 2nd reference atom, go to second step. To change 1st reference atom, go to first step. To cancel the second reference, go to second step (control middle-button) while picking outside any atom. To cancel the first reference, go to first step (shift middle-button) while picking outside any atom.
• Highlight (or unhighlight) nodes using control left-button.

All measured distances and angles are persistent. A line is drawn between nodes and the length is printed in the middle of the line. For angles, a small filled arc is also drawn with the angle value in degrees. To avoid this, uncheck the box (2) on the bottom of the pick tab. One can also remove all marks by clicking the "clear" button near this checkbox.

A table of picked nodes is kept (3). Use the Suppr key to remove a node from this history (this does not remove the node itself). The number and the type of the node is printed. Some other informations may appear, such as the spin orientation informations in spin mode (values are then changeable). The colour data is also print there, if any colour file has been loaded (see the colourise nodes entry). The checkbox of the second column is active if the node is highlighted. Use the buttons near (6) to highlight or unhighlight all the nodes in the history list.

The widgets on (4) are used to draw information directly on the rendering area. One can choose to draw data only on nodes listed in the above table or on all nodes. In version 3.5, for ASCII files, a label can be drawn on whatever node.

From version 3.5, the buttons in area (5) can be used to load or save an XML file containing a list of picked nodes. The highlight status and all distances can be stored in such a file also.

In any mode, right-button ends picking session and returns to observe mode.

Geometry modifier↑ Return to top

This is a simple interface to change the geometry. By left clicking on a node, it is possible to move it in the view plane or constrained along X, Y or Z axis (see the help frame for further explanations). This mode is convenient with the export to ASCII since then, the modified geometry can be saved into a file (use the export button and choose the ASCII export format). It is also possible to move several nodes at once. To do it, change the radio buttons (1) accordingly. The selected nodes are those that appear in the table (3) of the pick tab (see above).

Still on the geometry tab, one can add new nodes at a given position. Only chemical species already existing can be added. To remove nodes, pick one or several and click the minus button. Warning, it is not possible to cancel the removal (except when only one node has been removed).

Changing the basis set↑ Return to top

It is possible to change the basis set, i.e. define another bounding box, by selecting nodes that would be at vertices of the new basis set. The new origin is called O in the interface and the vertices at x, y and z directions are respectively called A, B and C.

One can choose the new vertices either by giving their id (see (1)) or by picking them directlty (see (2)). When the four vertices are chosen, one can apply the new basis set by clicking the apply button (3). All nodes outside the new box will be suppressed. This action cannot be undone.

From version 3.6, when the the four vertices are chosen, V_Sim draw lines along the new directions to give an idea of the new basis set. A warning can also be issued if the basis set would be indirect (see (4)).

Symmetry analyser↑ Return to top

When the ABINIT plug-in for V_Sim is compiled and loaded, there is a new tab in the inderactive dialog (see (1)). By default, the symmetries are not computed, to do it, click on the button (2). If the box is a primitive one, the corresponding space group and crystal symmetry are displayed near (3). Using a node id, or by clicking on one atom, one can highlight the equivalent atoms by symmetry, see (4).

From version 3.6, a list of symmetry operations are also listed with their names in a treeview near (3). One can also tune the tolerance on symmetry calculation, as defined by tolsym in ABINIT.

Drawing pairs↑ Return to top

To use pairs, it is mandatory to check the toggle button at the bottom of the main command panel, next to the "pairs" button. This last button is used to open a dialogue window to customise pair definitions.

The pair dialogue is used to create pairs and choose their characteristics and rendering aspects. Two pair models are available (see further).

The table (2) is used to list all possible pair definitions. In V_Sim, pairs are characterised by the two chemical species of elements they link, plus the distance in-between they are drawn. On the given example, pairs are drawn between all Mn and Ge nodes which distance is in 2.5 and 2.6. Since version 3.4.0, it is possible to define more than one distance criterion for a given chemical species couple (use buttons (4)). When a great number of chemical species are present, one can filter the list with the combobox (3). One can also (since version 3.5) use the toggle button (6) to hide all pair definitions that give no drawable pairs (min criterion greater or equal to max criterion).

The 'automatic' button (5) can be used to compute first neighbour pairs. Select one or more line in the table (2) and click the button (5). V_Sim compute the distance distribution for each selected line and take the distance boundaries that define the first pick in the distribution.

In the table (2), the first checkbox column is used to render or not a defined pair. The second checkbox column is used to print on the rendering area the distance of all pairs.

From version 3.6, pair style can be chosen per link, as shown on the right image. This is convenient to use pair links to highlight bonding characteristics like weak hydrogen bonding.

Drawing pairs as wires↑ Return to top

The wire pair rendering method draws pairs as simple flat lines. One can tune the width in pixels (1) and the line pattern (2). In addition, one can choose to colourise (3) the pairs according to their length (this choice is applied for all wire pairs).

Drawing pairs as cylinders↑ Return to top

The cylinder pair rendering method draws pairs as 3D cylinders. With the cylinder, it is possible to change the diameter (1) and an option (2) can be used to draw the pair in the colour of the element it represents instead of a specific one. In the former case, the bond is separated into two.

Analyse pair length distribution↑ Return to top

V_Sim can plot a distribution of pair length, also called g(r). The pair dialog has a new tab, called "distances" (1). This tab shows a graph with some widgets under. In the graph, depending on the filter (2), the curves represent the distribution of lengths for all elements or for a chosen one. In the image on the right, the filter is set to 'Si', so grey bars in the graph represent the g(r) for silicon with whatever other species. The coloured lines represent in green and dark grey the length distribution for silicon with silicon and silicon with hydrogen, respectively.

The range of x axis of the graph is modified by the two spin buttons (3). The integration step is tune with the last spin button of the line. The lower the value, the cruder will be the g(r).

One can highlight a region in the graph, using the range buttons (4). The area is drawn in violet on the graph. Below the range buttons (4), there are two measurement information detailing the number of pair integrated in the region, divided by the number of nodes of this element (giving a clue on the average number of neighbours). The second measurement provides the mean distance corresponding to the highlighted picks. On the graph the values of the picks are printed.

A check button (5) is provided to highlight on the rendering area the nodes that correspond to the lengths in the highlight region of the graph.

Playing with colours and light↑ Return to top

V_Sim stores colours in a combobox widget. Add a colour can be done by selecting the first row in this widget and adjusting then a new colour. Each color is defined by its 3 r(red) g(green) b(blue) components (each one being between 0. and 1.). The program may use the a(alpha or opacity) channel, but this is not very recommended since some strange artifacts can appears because of a lack of drawing ordering. Values may also be changed using some range button beneath the combobox. To add the new colour, click then on the "+" button besides the range ones.

However, the color of a given pixel will be modified by lighting (and fog: see above)

Here is the description given in the "OpenGL red book" (OpenGL Programming Guide _ Addison-Wesley Publishing Company)

The OpenGL lighting model considers the lighting to be divided into four independent components: ambient, diffuse, specular and emitted.

The ambient component is the light from that source that's been scattered so much by the environment that its direction is impossible to determine - it seems to come from all directions. Backlighting in a room has a large ambient component, since most of the light that reaches your eye has bounced off many surfaces first. A spotlight outdoors has a tiny ambient component; most of the light travels in the same direction, and since you're outdoors, very little of the light reaches your eye after bouncing off other objects. When ambient light strikes a surface, it's scattered equally in all directions.

Diffuse light comes from one direction, so it's brighter if it comes squarely down on a surface than if it barely glances off the surface. Once it hits a surface, however, it's scattered equally in all directions, so it appears equally bright, no matter where the eye is located. Any light coming from a particular position or direction probably has a diffuse component.

Specular light comes from a particular direction, and it tends to bounce off the surface in a preferred direction. A well-collimated laser beam bouncing off a high-quality mirror produces almost 100 percent specular reflection. Shiny metal or plastic has a high specular component, and chalk or carpet has almost none. You can think of specularity as shininess.

Emitted light is the simplest - it originates from an object and is unaffected by any light sources.

The program has installed one light source (up right back you!) and the lighting modifies each of the rgb component by using 5 factors:

• f.amb : factor of ambient light
• f.dif : factor of diffuse light
• f.shi : coefficient of shininess for the specular light
• f.spe : factor of specular light
• f.emi : factor of emitted light

Drawing box and axes↑ Return to top

You can draw the box around the system by selecting the check-box located in the sub-panel Box/Axes, another check-box is available to draw the axes. One can control their thickness, their colour and their line pattern. The color can be added to the list of known colours with the '+' button.

Playing with fog↑ Return to top

Fog is the process in which the nominal color is progressively mixed with the fog color as a function of its distance from the eye.

                0                                           1
eye :) ----->   [xxxxxxxxxxxxxx OBJECT xxxxxxxxxxxxxxxxxxxxx]
	  
                        ^                        ^
                        |                        |
                        |                        |
                        start                    |
                                                 end
	  

There is no fog for distances nearer than start Fog begins at start, is complete at end.

You can play with start and end values:

• if you wish NO FOG at all, push end at 1, and start at 1 (minus eps)
• if you wish FULL FOG (!!!), push start at 0, and end at 0 (plus eps)
• if you wish MAX CONTRAST, try the following steps:
  • choose background as fog color
  • push start at 0 and end at 1
  • look at the nearest object point; push gently start toward the right : the observed point should become brighter. Stop when brightening no longer increases
  • look at the furthest object point; push gently end toward the left : the observed point should become more and more faded in the fog. Stop when it just disappears in the fog
  • eventually choose now black as fog color

You can also choose fog color. Use background to have nice fog.

Display a legend↑ Return to top

In the "axes" subpanel, one can check a box to display a legend in the rendering window. This legend display the list of declared elements, their current representation, their name and the number of corresponding nodes.

The legend in also exported in SVG.

Browsing through current directory↑ Return to top

In the 'Browser' subpanel, all valid files for the current rendering method, are listed and Bitmapcan be selected. The directory scanned is the current working directory, but it can be changed using the button on the left (3). Using the zoom in button there, it is also possible to show a recursive browsing inside the directories (as shown on the screenshot). The listed files can be restricted to some using the filter (2), on top. This filter try to match names with the '*' character as a wild card.

Files to rendered can be selected, by checking the box in the left column. Then with the arrows (4), one can quickly browse through these files. Double clicking on a file select it and render it also. Use the buttons (5) to select all or unselect all files.

The elements on (6) are used to automatically load selected files one after another. This is convenient to view like an animation. To do it, click on the play button. All action are still working during the playing. For instance, one can still move the camera, pick an atom, change a plane position... There are three possible ways to play the selected files. The is to return to first file when the last is reached. The second is to stop when all files have been reached and the last is to play then back and forward.

The button (7) is used to dump all the selected files in the browser. When the directory and the file name is specified, a '%0xd' is required in the name to be replaced by the number of each exported file. For example if toto%03d.pdf is specified, the program will dump all selected files with name like this : toto000.pdf, toto001.pdf...

From version 3.5, two arrows (next and back) have been added to navigate between already opened directories, as in a file explorer.

Colourise nodes - basics↑ Return to top

V_Sim has the ability to override the color of elements and to colourise node per node when an external data file is loaded. This file is a simple ascii file with figures in columns. It can have as many columns as one wishes, but the number of lines should match the number of nodes. Go to the "colourise with data" subpanel and check the checkbox (1) to use this functionality. Then open a file using the button (2) or check the other "Auto load" checkbox. This last box is used to automatically load an associated data file whenever an atomic file is loaded. V_sim then tries to match the atomic file name, substituting the extension with dat.

The number of read columns is printed in the little status bar at the bottom of the subpanel.

From version 3.5, it is also possible to use the colourisation without specifying an external file. See the "choose a shade" part further for details.

Colourise nodes - normalise data↑ Return to top

The loaded data can have whatever range possible. But to transform these values to colours, they must be transformed to [0;1]. This is done in the normalise process (1). It can be done automatically (default) or boundaries for the linear transformation can be given by hand (2). When the transformation is done automatically, in each columns, minimum value is transformed to 0 and maximum is transformed to 1. On the contrary, when set manually, boundaries are valid for all columns. Values are clamped into [0;1] in manual mode.

A little array is also given to remind the minimum and maximum values in each columns (3).

Colourise nodes - choose a shade↑ Return to top

Once input data are transformed into [0;1], they can be used to colourise nodes. One can use preset shades (variations are read from coloumn 1 by default), see (1). Or one can define the linear transformation from input data to colours. Colours can be coded into RGB (red-green-blue) or into HSV (hue-saturation-value). Each channel is then a linear combination of input data: for instance in the given screenshot, hue (H) is equal to 0.67 - 0.67 * (values read in column 1), whereas saturation (S) is a constant set to 1.

It is possible then to create complex shade or to directly choose the colours from the input file: create then a file with three columns, each one for RGB for instance, and set R=0+1*col1, G=0+1*col2 and B=0+1*col3. If there is only one column implied in the transformation, a small representation of the resulting shade in drawn.

From version 3.5, it is possible to choose the x, y or z coordinates of nodes as a data input for the colourisation. In that case a data file is not necessary.

Colourise nodes - post processing↑ Return to top

The first post-processing tool is used to hide nodes depending on values read from one column. To do it, check the "hide elements" box, choose the column from which values are read and set the upper bound for drawn nodes.

The second processing tool can be used to change the size of each node according to external data. To do this, check the second box and choose a column of the input file.

Colourise nodes - command line options↑ Return to top

• -c --colorize file

  A file to render must be given, then it enables the colourise with data mode and load the given file. By default the colour transformation is set to the first preset shade.

• -u --use-column l:m:n

  The -c option must be given. This option is used to choose which columns are used in the transformation for the three colour channels. Use l=1 to set the R (or H) channel to read data from column 1. Use special value 0 to set a constant instead of a value from a column.

• -d --color-preset id

  The -c option must be given. This option is used to set a preloaded shade. id are integer ranging from 0. The -u option has a priority over this option.

Draw planes - basics↑ Return to top

One or several planes can be drawn. These planes can be fully opaque or has a degree of transparency. They can be use to highlight a region or to hide nodes. To enable the plane mode, go to the "Drawing planes" subpanel and check the appropriated checkbox.

Plane definitions are given as a list. To change some of the geometric definition, select one or several planes and use the buttons (2). The normal line gives the coordinates of the normal vector to the plane. The distance line gives the distance between the plane and the origin of the box. Finally a select element gives the opportunity to change the colour among preset ones or to choose a new one. To use the hide capability of a plane, check the hide checkbox on its line. It hides all nodes on one side of the plane. To hide the other side, check the invert checkbox. Planes are not necessary rendered to hide element.

The choice on (1) is available when several planes are drawn. It set how they interact with each others when hiding nodes. In "union" mode, a node hidden by at least one plane is actually hidden, whereas in "intersection" mode, a node must be hidden by all planes to be actually hidden.

Finally, the button (3) is used to make the camera looks in the direction of the normal of the selected plane. It can be convenient to set the view following Miller's indexes.

Draw planes - other tools↑ Return to top

The tab called "advanced tools" is used to animate one plane. Select one, then choose the minimum distance, the maximum distance and the step then click on the play button. The distance characteristic of the selected plane is then automatically varied in the given range. All other actions are still possible during this animation, especially the observe action.

The last tab (file tools) is used to load or to save a plane file.

Draw planes - command line options↑ Return to top

• -p --planes file

  Definitions of planes can be saved as XML files, this option is used to load such files. When this option is given the plane mode is enabled and hiding policy is applied.

Display surfaces - Overview↑ Return to top

This module allows you to visualise surfaces along with a previously loaded Atomic or Spin configuration. To display surfaces in the currently loaded config, check the "Use isosurfaces" box in the "Isosurfaces" subpanel. Surfaces can be drawn directly from their polygons description or they can be interpolated from a scalar field.

The description of the file format used to describe polygons of one or several surfaces is detailled on the page about formats. The description of scalar field (or potential files) is also done on this page. With the help of the ETSF plug-in, files respecting ETSF specifications for densities can be loaded.

It is possible to create a .surf file using pot2surf or combine several .surf files into a single .surf file using the surf file merger. To do it, click on the "convert" button.

Either surf files or density files are loaded using the "load" button. If the box (1) is checked, whenever a configuration is loaded V_Sim try to load a surface or a density file with the same name, replacing its extension by .surf or .dat.

Its is possible to load several files at one time. All loaded ones are present in a treeview, where their types and names are printed. In case of scalar field files, the mininum and the maximum values are reminded (2). For each surface, the check box in the column (3) is used to draw it or not. Use the buttons (8) to check or uncheck all surfaces.

The next column (4) is used to print the value of the potential from which the surface has been created. This value is editable in the case of scalar field files. To do it, click on the value and change it manually (all editable cells are printed in blue). On can change the colour of a surface or of all surfaces, using the buttons (6). The second button (change all surfaces colours) has a special behaviour. If a surface is selected, all surfaces of the same file are also changed. If nothing is selected, then all surfaces from all files are changed. More over, the colour property is associated to the surface name, so two surfaces share the same name, changing the colour property of one will affect the colour of the other. As potential values, names are editable by clicking in the cell.

The buttons (7) are used to add or remove surfaces. Addition is only possible for scalar field files. To do it, select the file in the tree view and click the "+" button. It will create a surface will the mean value of potential. Change it by clicking on the value and setting it manually. The remove button works for both surface files and scalar field files. When using it, surfaces are removed from memory and the files are left unchanged. Removing a file from the treeview removes all depending surfaces.

The box (5) can be used when the system lags because of numerous transparent surfaces. When unchecked, surfaces are not redrawn when the camera is moved with the mouse. It leads to graphical artifacts that disappear as soon as movement with the mouse is stopped.

Display surfaces - pot2surf↑ Return to top

The pot2surf tool allows you to create isosurfaces given density data. It can be found by clicking the "Convert" button under the "Isosurfaces" panel. In order to use it, it's first needed to load a .pot file which will be immediately parsed by V_Sim to retrieve its min and max potential values. You can then set surfaces to build using the "+" button. A default value for the surface and a default name are automatically set for the surface, but you can change them by double clicking them. All surfaces names should be unique and your surfaces values shouldn't be the exact pot_min or pot_max values because pot2surf will fail if it can't build one of the surfaces. Once you've specified surfaces to build, you must select a .surf file to write. You can then click the "Build" button to build the target .surf file you specified. An option allows you to make the newly created file autoload in V_Sim's "Isosurfaces" panel. You can also save/load a pot2surf configuration as an instruction file using the toolbar buttons.

Display surfaces - Surf file merger↑ Return to top

The surf file merger allows you to build a single .surf file from multiple ones. It can be found in a tab next to the pot2surf module. To create a new surf file, you need to load each file one after another (like a movie) on the top area of the window. V_Sim automatically parses the surf file you selects to find the surfaces that are contained within the selected file. you can then add surfaces to the bottom area by clicking the "+" button after having selected surfaces in the top list (you can even ctrl or shift-select them). Once you've finished adding surfaces, click the "Build" button to generate a new .surf file ready to load in V_Sim.

Display surfaces - Command line options↑ Return to top

• -f --scalar-field file

  A file to render must be given, then it enables the surface mode and load the given scalar field file. By default no surface is created for this file. Use the -iso-values option to add surfaces.

• -v --iso-values v[:v]

  To be used in conjunction with --scalar-field, it creates surfaces for the given values. As many values as required can be created, separating given values by ":". It is also possible to associate names to loaded values (default is "Surface id"), appending "#name" after the value, e.g. 0.25#green:0.75#blue. Associate names to value is convenient to set colour properties for a surface, using those stored in the v_sim.res file.

• -i --iso-surfaces file

  A file to render must be given, then it enables the surface mode and load the given surface file. All surfaces described are loaded and rendered.

• --fit-to-box val

  Surface files and scalar field files have their own description of bounding box. This description may not match the one from the atomic or spin file. By default the created surfaces are modified to fit the box of the atomic or spin file. Use this option and set val to FALSE to keep the bounding box of surface untouched.

Draw scalar fields as colour maps↑ Return to top

When a scalar field is loaded, it is possible to draw a coloured cutting plane. Go to the 'Coloured maps' subpanel, having already loaded a scalar field in the 'Isosurfaces subpanel' and having created a plane in the 'Planes' subpanel. None of the two previous modules need to be activated, just create a plane and load a scalar field. Then, they will be available in the combobox selectors. To draw the coloured map, click on the 'build' button. The map remains as long as the plane and the scalar field are loaded.

A legend is drawn in addition to the coloured map, showing the colour range. On this legend, two lines are drawn to represent the values of the minimum and maximum values currently rendered in the cutting plane. From version 3.6, additional smaller lines are drawn to represent the values of the isolines, if any.

The colour interpolation is a simple linear one, so loose density mesh may result in poor colour contours.

Advanced options↑ Return to top

Different options are available to tune the map:

• The map is drawn (from version 3.6) with an adaptative algorithm that can be visible using the wire rendering in the OpenGL tab. To increase (or decrease) the finest level of triangles, use the general OpenGL precision available in this OpenGL tab. On the contrary, the button (1) is used to tune the level of adaptiveness. At 100%, this is the default level. When 200% is reach, there is no adaptiveness and at 10%, the rendering is crude.
• The colour transformation (2) may be linear, logarithmic or logarithmic for values around zero (like a density of polarisation for instance). This is available from version 3.5.
• One can plot contour lines on the map (3), since version 3.4. The colour of the lines are customisable. When the checkbox is unset, the colours are the inverse colour of the value they represent. The values of the contour lines are equally distributed in between the range of drawn values for the current plane. From version 3.6, the chosen values for the contour lines are kept fixed if the normalisation (4) is manual.
• The normalisation (4) of the density can be automatic (i.e. transformed from min / max values into [0;1] or manual (but clamp to [0;1] anyway), as for the colourisation capability. This is available from version 3.5.

Exportation options↑ Return to top

It is possible since version 3.5 to draw as many map as required, using the "+" button (one can remove maps using the "-" button). All maps share the same scalarfield and shade colourisation but are projected on different planes. From version 3.6, the contour values are common to all planes at once.

One can save any map into a PDF file or a SVG file. The legend is not exported yet, but the contour are there.

Command line options↑ Return to top

Command line options for the coloured maps are:

• -b --build-map id

  The argument fileToRender must be given, as the '--planes', '--color-preset' and '--scalar-field' options used, then the given plane 'id' is replaced by a coloured map using given scalar field and shade. 'id' ranges from 0.

• --log-scale id

  If given, plots are done with the logarithm scale method that is given (range from 0).

• -n --n-iso-lines val

  When positive, val isolines are plotted on the coloured map.

• --color-iso-lines [R:G:B] or auto

  When given, generated iso-lines are colourised [R:G:B] or auto with the values. The specific value 'auto' will produced iso-lines in inversed colours.

• --map-precision prec

  From version 3.5, specify the precision parameter for the quality of the map drawing.

• --map-clamp min:max or auto

  From version 3.6, specify the scaling parameters for the input scalar field, either by hand (min:max) or automatically using the widest range of the scalar field.

Show geometry differences between two files↑ Return to top

When studying geometry evolution, it can help to visualise the moving nodes. It is possible by printing arrows showing the displacements of nodes. To do it, check the box (1). Then, each time a new file is loaded, V_Sim will substract position of nodes two by two (using the node ordering of the input file), taking into account the periodic boundary conditions (if any). If the two files don't have the same number of nodes, the error is silently ignored.

The geometry differences are drawn by arrows centered on previous node positions. The length of the arrow is proportional to the displacement. For the fraction of the biggest displacements, the length is printed beside the arrow.

There are several keys in the resource file to handle the scaling of arrows.

From version 3.6, checking the box (2), one can ask V_Sim to reorder the new file with the previous. Nodes of the new file are re-indexed by matching the closest node in the previous file.

From version 3.6, when exporting in ASCII, the values of all displacements are dumped as a meta data information.

Show paths described by a set of files↑ Return to top

When studying geometry evolution, like diffusion, saddle points..., V_Sim can help to visualise the paths used by the nodes to move. Like the geometry differences, this is a multi-file action. Each time a new file is loaded, V_Sim can add the displacements of each node to a set of lines representing the displacements. To do it, toggle the button (2). When one want to change the file but not extend the path, simply uncheck this button (2). Paths are displayed as long as check button (1) is active. To clear the current paths, click on button (3). When (2) is toggle, it is convenient to use the browser to extend the path. In that case, the browser displays a warning message that displacements will be saved. Changing directory automatically untoggle path recording.

If the file has support for total energy value (see exporting in ASCII), the paths can be colourised with a colour scheme (4) according to the energy of the system at a given position.

The XML file format of V_Sim can store existing paths or load previously saved ones using the buttons (5).

Bitmap exportations↑ Return to top

V_sim can export to bitmap images. Some vectorial formats are available (PDF for instance) but they are just containers for bitmap data. During exportation, it is possible to choose a different size compared to the one used by the view (1). The rendering is done into memory and will not use the hardware capability of the video card. This may imply slowness for big exportations.

• PS dump produces a very high quality PostScript file (with all colours as shown on the screen). It is a compressed file; nevertheless, its size could be prohibitive. Using the expander 'file format option', one can reduce the colour table to 256 values. This produces a smaller file, such as GIF.
• GIF dump produces a GIF file (with at most 256 colours as required by the GIF specification). Thus, the quality could be least; however, its size is probably reasonable. Ask an expert to convert such a GIF file to other formats.
• PDF dump produces a Portable Document File with true colours. It uses a lossless compression for the image.
• TIFF dump produces a Targa Interchange File with true colours. As PDF, it uses a lossless image compression.
• PNG dump produces a Portable Network Format file with true colours. It also uses a lossless compression.
• JPEG dump produces an image with true colours and adaptive lossy compression. To tune the quality of produced image, choose the JPEG format and expand the 'file format option' (2). Then choose a quality. 90 is an almost lossless compression.

• -e --export file

  Export the loaded file to the given argument, guessing the format with the argument extension.

ASCII exportations↑ Return to top

It is also possible to export any loaded file to the ASCII format (native text format of V_Sim with bounding box capability). This exportation can be interesting after having moved the atoms with the interaction move action (see the manual).

By default the unit used to export the coordinates are the one currently in use. There are several options for this format:

• Do not export, or export as comments hded nodes (by planes or other eanings).
• Keep the origin box, in case of box expansion.
• Convert the coordinates to reduced values.
• Use the lengths and angles definition for the box.
• Sort the nodes, grouping per element (instead of keeping the input ordering).

From version 3.6, in case of a difference between two files the differences per node are exported as a keyword.

XYZ exportations↑ Return to top

The XYZ exportation follows the same behaviour than the ASCII exportation, with less options due to the constraints on the format.

CIF exportations↑ Return to top

Using OpenBabel, it is possible to export in all format supported by the library. The format is selected by the extension used for the file.

Using a command line exportation with OpenBabel is typically done by:

./v_sim -o fileFormatId=1 -e example.cif example.ascii

ABINIT exportations↑ Return to top

One can generate an ABINIT input file, regarding the crystal part.

Vectorial exportations↑ Return to top

Introduced in version 3.4.0, the SVG allows a basic vectorial exportation. It requires Cairo to work and should be compiled at build time. Currently, it only supports the exportation of atoms (no spin), the bounding box, the pairs and the axes. The pairs exportation does not follow the user choices of style, but colours are respected.

From version 3.6, the fog is supported. The colourisation and post-treatment comming from a data file is also supported.

Scripting capabilities↑ Return to top

When compiled with the PythonGI plug-in, one can load (2) and execute a Python script directly from the user interface in a special tab (1). Scripts should begin with:

from gi.repository import v_sim
          

To acces the current rendered VisuData object, one can use the following lines:

# To get the rendering window.
render = v_sim.uiMainClass_getDefaultRendering()
# To get the rendered object.
data = render.getVisuData()
          

Parameters file↑ Return to top

It is a file which contains some default parameters. It is read ONCE at startup. These options are relative to the interface and not the rendering itself.

When V_Sim starts,

• it looks in your current directory for a file named: v_sim.par and if it finds it, it reads it and don't search further more.
• it search a file v_sim.par in the $XDG_CONFIG_HOME/v_sim directory.
• finally, it falls back to the default installation path ($prefix/share/v_sim).

During a V_Sim session, NO parameter file will be read! However, you can save current parameters in any file of your choice. To do it, click on the 'config. files' button on the command panel and choose the 'parameters' tab. A full list of parameters is available on the sample page.

Resources file↑ Return to top

This file is made to be able to redraw exactly a view with the same camera orientation, element colours... So it is convenient to save several of these files in different places, especially in archives.

When V_Sim starts,

• it looks in your current directory for a file named: v_sim.res and if it finds it, it reads it and don't search for another one.
• it search a file v_sim.res in the $XDG_CONFIG_HOME/v_sim directory.
• finally, it falls back to the default installation path ($prefix/share/v_sim).

During a V_Sim session, you can scan any resource file (with any name). You can also save current resources in any file of your choice. To do it, click on the 'config. files' button on the command panel and choose the 'resources' tab. A full list of resources is available on the sample page.

It is also possible to force a given file (i.e. a file with a name different from v_sim.res) using the following command line option (since 3.4.0):

• -r --resources file

  Load the given resources file on startup instead of looking for a valid resources file in the standard locations.